3.3: REST Services

You can setup REST service proxies which can be invoked to receive response data. This response data can be bound to your page controls. In order to create and configure your REST service, click the REST Service button on the Data Sources tab and follow the instructions. REST services are configured using an XML fragment to provide dynamic capabilities, including the ability to determine the POST Method, URL, Header attributes and security settings during runtime. See how to use REST services with WebMaker WebMaker has the capability to access Rest-based services without any traditional programming. This can be achieved using a simple XML control fragment, which is processed at runtime to define the various dynamic elements such as the location URL, http request method and other parameters for the remote service. This can be achieved using the normal rules mechanism within Controllers. WebMaker can easily handle REST Services using both XML and JSON message formats. The first step is to setup a proxy controller for the remote Rest Service. In order to achieve this, an 'empty' (no rules processing) Proxy controller needs to be setup. This can be achieved by opening the Project Settings tab and clicking on the Runtime Patterns tab. Typically, click on the Model layer to set-up a Remote Proxy Controller that will be mapped to the physical Rest Service. Type in the New Filename for the reference to the controller you want to call, e.g. {RemoteControllerName_Rest_Proxy} and click on the Clone Pattern button. This will display another screen that enables the selection of the Base Pattern to be used - In this case the Remote_Service_Proxy.xml file. Finally, click on the Clone Pattern button to create the controller. Once this is done, open the Test Settings and select the Agent Types menu option. Click on the Agent Id for the controller just created, and then change its Agent Type to Web Service Proxy. The Service Type field should be correctly defaulted to HTTP Service. Enter the Web Service URI as the full URL for the Rest Service. Ensure you tick the Allow Advanced Features option if you need to dynamically alter the URL for the Rest Service at runtime, or need to pass dynamic Parameters to the service. Then click on the Change Agent Type to commit the changes. Finally, this proxy controller, in the model layer, can then be configured for invocation from other controllers using an Invoke Service action. This proxy controller acts as a gateway to the actual Rest Service. This means that the URL (or at least the static part of the URL) can be amended in the External Calls section within the Publish Settings for different publication targets. An HttpHeader fragment can be used to dynamically set http header attributes and direct payloads to dynamically constructed URLs. The HttpHeader fragment will typically be created in a controller within the Access Service or Controller layers, calling a proxy to a remote URI. This fragment should be included in the request payload to be sent for the External Call. If the Advanced? option is ticked then WebMaker will search for the HttpHeader fragment in the FactBase and parse it to create a URI dynamically, set the http attributes before sending the payload. After processing, the HttpHeader fragment is removed from the message before the payload is sent. The following example XML fragment can be placed within the payload to change the default behaviour:

<xg:HttpHeader xmlns="http://www.hyfinity.com/xgate" xmlns:xg="http://www.hyfinity.com/xgate">
    <xg:url action="" merge_option="replace" request_method="GET">http://anyValidUrlString</xg:url>
    <xg:params>
        <xg:param name="command">login</xg:param>
        <xg:param name="error_dest">client</xg:param>
    </xg:params>
    <xg:attributes>
        <xg:attribute name="HTTPHeaderAttrib1">attribute value</xg:attribute>
        <xg:attribute name="HTTPHeaderAttrib2">attribute Value</xg:attribute>
    </xg:attributes>
</xg:HttpHeader>

The params will be appended to the URL in name=value pairs separated by "&" after a "?" has been inserted between the URL and the params. e.g. http://anyValidUrlString?command=login&error_dest=client The attributes will be set in the request http header before a request is made to the URL. The name attribute indicates the name of the http header attribute and the value is the value to be set for this header attribute. If your service deals with JSON formatted data, then you can use additional rule actions to convert the JSON string to XML, and vice versa. If your service returns a JSON response, then the JSON string will be available in your Controller rules within a non_xml_content element in the service response. To convert this into a structured XML format for easy binding to page fields you would use a JSON to XML Conversion action. If you are trying to post a JSON request to a service then you will need to configure the HTTPHeader as described above so that a Content-Type request header of application/json will be set. The XML data to be sent should be converted to JSON using an XML to JSON conversion action, and placed within a json_request element. The HttpHeader fragment should also be placed within the json_request before this element is sent to the Rest Service Proxy.